<div class="bd-content">
<h1 class="bd-title" id="content">弹出框（Popover）插件</h1>
          <p class="bd-lead">Bootstrap 弹出框的文件与实例，类似 iOS 上的风格，可加在网页上的任何元素上。</p>
          <h2 id="overview">概览</h2>

<p>使用弹出框插件时应了解的事情如下：</p>

<ul>
  <li>弹出框依靠第三方函数库 <a href="https://popper.js.org/">Popper.js</a> 进行定位。 在 Bootstrap 弹出框工作之前，你必须包含 <a href="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.14.3/umd/popper.min.js">popper.min.js</a>，或者使用 <code class="highlighter-rouge">bootstrap.bundle.min.js</code> / <code class="highlighter-rouge">bootstrap.bundle.js</code>，这已经包含 Popper.js 可以直接运作。</li>
  <li>弹出框需要工具提示插件作为依赖。</li>
  <li>如果你自行编译 JS，记得 requires.util.js。</li>
  <li>由于性能原因，弹出窗口是具有选择性的，因此您必须自己初始化它们。</li>
  <li>零长度 <code class="highlighter-rouge">title</code> 和 <code class="highlighter-rouge">content</code> 值是不会显示一个弹出框。</li>
  <li>指定 <code class="highlighter-rouge">container: 'body'</code> 以避免在更复杂的元件（如我们的 input 群组，按钮组等）中出现问题。</li>
  <li>触发隐藏元素上的弹出窗口将不起作用。</li>
  <li><code class="highlighter-rouge">.disabled</code> 或 <code class="highlighter-rouge">disabled</code> 元素弹出框的触发必须在外层元素上。</li>
  <li>当从跨越多行的超链接触发时，弹出框将被居中。在你的 <code class="highlighter-rouge">&lt;a&gt;</code> 上使用 <code class="highlighter-rouge">white-space: nowrap;</code> 来避免这种行为。</li>
  <li>必须先隐藏弹出框，然后才能从 DOM 中删除相应的元素。</li>
</ul>

<p>都明白了？太好了，让我们通过一些例子看他们是如何运作的。</p>

<h2 id="example-enable-popovers-everywhere">实例：在任何地方添加弹出框</h2>

<p>在页面上初始化所有弹出框的一种方法是通过它们的 <code class="highlighter-rouge">data-toggle</code> 属性来选择它们：</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
  <span class="nx">$</span><span class="p">(</span><span class="s1">'[data-toggle="popover"]'</span><span class="p">).</span><span class="nx">popover</span><span class="p">()</span>
<span class="p">})</span></code></pre></figure>

<h2 id="example-using-the-container-option">实例：使用 <code class="highlighter-rouge">container</code> 选项</h2>

<p>当你在父元素上有一些干扰弹出框的样式时，你需要指定一个自定义的 <code class="highlighter-rouge">container</code> 容器，以便弹出框的 HTML 显示在该元素中。</p>
<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
  <span class="nx">$</span><span class="p">(</span><span class="s1">'.example-popover'</span><span class="p">).</span><span class="nx">popover</span><span class="p">({</span>
    <span class="na">container</span><span class="p">:</span> <span class="s1">'body'</span>
  <span class="p">})</span>
<span class="p">})</span></code></pre></figure>

<h2 id="example">实例</h2>

<div class="bd-example">
<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
</div>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;button</span> <span class="na">type=</span><span class="s">"button"</span> <span class="na">class=</span><span class="s">"btn btn-lg btn-danger"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">title=</span><span class="s">"Popover title"</span> <span class="na">data-content=</span><span class="s">"And here's some amazing content. It's very engaging. Right?"</span><span class="nt">&gt;</span>Click to toggle popover<span class="nt">&lt;/button&gt;</span></code></pre></figure>

<h3 id="four-directions">四个方向</h3>

<p>有四种选择：顶部，右侧，底部和左侧对齐。</p>

<div class="bd-example popover-demo">
  <div class="bd-example-popovers">
    <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
      Popover on top
    </button>
    <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
      Popover on right
    </button>
    <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
      Popover on bottom
    </button>
    <button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="Vivamus sagittis lacus vel augue laoreet rutrum faucibus.">
      Popover on left
    </button>
  </div>
</div>

<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;button</span> <span class="na">type=</span><span class="s">"button"</span> <span class="na">class=</span><span class="s">"btn btn-secondary"</span> <span class="na">data-container=</span><span class="s">"body"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">data-placement=</span><span class="s">"top"</span> <span class="na">data-content=</span><span class="s">"Vivamus sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</span>
  Popover on top
<span class="nt">&lt;/button&gt;</span>

<span class="nt">&lt;button</span> <span class="na">type=</span><span class="s">"button"</span> <span class="na">class=</span><span class="s">"btn btn-secondary"</span> <span class="na">data-container=</span><span class="s">"body"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">data-placement=</span><span class="s">"right"</span> <span class="na">data-content=</span><span class="s">"Vivamus sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</span>
  Popover on right
<span class="nt">&lt;/button&gt;</span>

<span class="nt">&lt;button</span> <span class="na">type=</span><span class="s">"button"</span> <span class="na">class=</span><span class="s">"btn btn-secondary"</span> <span class="na">data-container=</span><span class="s">"body"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">data-placement=</span><span class="s">"bottom"</span> <span class="na">data-content=</span><span class="s">"Vivamus
sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</span>
  Popover on bottom
<span class="nt">&lt;/button&gt;</span>

<span class="nt">&lt;button</span> <span class="na">type=</span><span class="s">"button"</span> <span class="na">class=</span><span class="s">"btn btn-secondary"</span> <span class="na">data-container=</span><span class="s">"body"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">data-placement=</span><span class="s">"left"</span> <span class="na">data-content=</span><span class="s">"Vivamus sagittis lacus vel augue laoreet rutrum faucibus."</span><span class="nt">&gt;</span>
  Popover on left
<span class="nt">&lt;/button&gt;</span></code></pre></figure>

<h3 id="dismiss-on-next-click">下次点击移除</h3>

<p>使用 <code class="highlighter-rouge">focus</code> 类以便用户进行下一次点击时移除这个弹出框。</p>

<div class="bd-callout bd-callout-danger">
<h4 id="specific-markup-required-for-dismiss-on-next-click">下一步点击所需的具体标记</h4>

<p>为了正确的跨浏览器和跨平台，你必须使用<code class="highlighter-rouge">&lt;a&gt;</code> 标签，而不是 <code class="highlighter-rouge">&lt;button&gt;</code> 标签，你还必须包含一个 <code class="highlighter-rouge">tabindex</code> 属性。</p>
</div>

<div class="bd-example">
<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
</div>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;a</span> <span class="na">tabindex=</span><span class="s">"0"</span> <span class="na">class=</span><span class="s">"btn btn-lg btn-danger"</span> <span class="na">role=</span><span class="s">"button"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">data-trigger=</span><span class="s">"focus"</span> <span class="na">title=</span><span class="s">"Dismissible popover"</span> <span class="na">data-content=</span><span class="s">"And here's some amazing content. It's very engaging. Right?"</span><span class="nt">&gt;</span>Dismissible popover<span class="nt">&lt;/a&gt;</span></code></pre></figure>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'.popover-dismiss'</span><span class="p">).</span><span class="nx">popover</span><span class="p">({</span>
  <span class="na">trigger</span><span class="p">:</span> <span class="s1">'focus'</span>
<span class="p">})</span></code></pre></figure>

<h3 id="disabled-elements">禁用的元素</h3>

<p>具有 <code class="highlighter-rouge">disabled</code> 的元素是不能产生互动的，这意味用户不能使用 hover 及点击触发弹出(或工具提示)，如果想要添加，你使用 <code class="highlighter-rouge">&lt;div&gt;</code> 或 <code class="highlighter-rouge">&lt;span&gt;</code> 包裹并覆盖 <code class="highlighter-rouge">pointer-events</code> 在禁用的属性上。</p>

<p>对于禁用的弹出框，你也许倾向使用 <code class="highlighter-rouge">data-trigger="hover"</code> 来直接为用户提供视觉回馈，因为用户不会去点击禁用的元素。</p>
<div class="bd-example">
<span class="d-inline-block" data-toggle="popover" data-content="Disabled popover">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled="">Disabled button</button>
</span>
</div>
<figure class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">"d-inline-block"</span> <span class="na">data-toggle=</span><span class="s">"popover"</span> <span class="na">data-content=</span><span class="s">"Disabled popover"</span><span class="nt">&gt;</span>
  <span class="nt">&lt;button</span> <span class="na">class=</span><span class="s">"btn btn-primary"</span> <span class="na">style=</span><span class="s">"pointer-events: none;"</span> <span class="na">type=</span><span class="s">"button"</span> <span class="na">disabled</span><span class="nt">&gt;</span>Disabled button<span class="nt">&lt;/button&gt;</span>
<span class="nt">&lt;/span&gt;</span></code></pre></figure>

<h2 id="usage">用法</h2>

<p>通过 JavaScript 添加弹出窗口:</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#example'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="nx">options</span><span class="p">)</span></code></pre></figure>

<h3 id="options">选项</h3>

<p>选项可以通过 data 属性或JavaScript传递。 对于 data 属性，请将选项名称附加到 <code class="highlighter-rouge">data-</code>上，如 <code class="highlighter-rouge">data-animation=""</code>。</p>

<table class="table table-bordered table-striped">
  <thead>
    <tr>
      <th style="width: 100px;">名称</th>
      <th style="width: 100px;">类型</th>
      <th style="width: 50px;">默认</th>
      <th>描述</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>animation</td>
      <td>boolean</td>
      <td>true</td>
      <td>将 CSS 渐变应用到弹出框</td>
    </tr>
    <tr>
      <td>container</td>
      <td>string | element | false</td>
      <td>false</td>
      <td>
        <p>
        将弹出框加到特定元素。例如：<code>container: 'body'</code>。该选项特别有用，因为它允许你将触摸屏定位在触发元素附近的文字内容 - 这将防止在画面调整大小期间弹出的提示远离触发元素。</p>
      </td>
    </tr>
    <tr>
      <td>content</td>
      <td>string | element | function</td>
      <td>''</td>
      <td>
      <p>如果 <code>data-content</code> 属性不存在，则为预设内容值。</p>
      <p>如果给出一个函数，它将被调用，其<code>this</code> 引用设置为弹出框附加到的元素。</p>
      </td>
    </tr>
    <tr>
      <td>delay</td>
      <td>number | object</td>
      <td>0</td>
      <td>
        <p>显示和隐藏弹出框的延迟（ms） - 不适用于手动触发类型</p>
        <p>如果提供了一个数字，则将延迟应用于隐藏/显示</p>
        <p>事件结构是：<code>delay: { "show": 500, "hide": 100 }</code></p>
      </td>
    </tr>
    <tr>
      <td>html</td>
      <td>boolean</td>
      <td>false</td>
      <td>
      将HTML插入到弹出框中。 如果是 false，那麽将使用 jQuery 的 <code>text</code> 方法将内容插入到 DOM 中。如果你担心 XSS 攻击，请使用文字。</td>
    </tr>
    <tr>
      <td>placement</td>
      <td>string | function</td>
      <td>'right'</td>
      <td>
      <p>如何定位彈出提示框 - auto | top | bottom | left | right。<br />指定 <code>auto</code> 时，将动态重新定位弹出框。</p>
      <p>当函数用于确定位置时，将使用弹出框 DOM 节点作为其第一个参数并将触发元素 DOM 节点作为其第二个参数来调用。 <code>this</code> 将被设为弹出框实例。</p>
      </td>
    </tr>
    <tr>
      <td>selector</td>
      <td>string | false</td>
      <td>false</td>
      <td>
      如果提供了选择器，弹出框将被委派给指定的目标。实际上，这用于动态 HTML 来扩增弹出框。 请参阅<a href="https://github.com/twbs/bootstrap/issues/4215"> 此 </a> 和 <a href="https://jsbin.com/zopod/1/edit">一个讯息实例</a>。</td>
    </tr>
    <tr>
      <td>template</td>
      <td>string</td>
      <td><code>'&lt;div class="popover" role="tooltip"&gt;&lt;div class="arrow"&gt;&lt;/div&gt;&lt;h3 class="popover-header"&gt;&lt;/h3&gt;&lt;div class="popover-body"&gt;&lt;/div&gt;&lt;/div&gt;'</code></td>
      <td>
        <p>创建动态提示框时使用的基本 HTML </p>
        <p>动态提示框的 <code>title</code> 将被注入到 <code>.popover-header</code> 中。</p>
        <p>动态提示框的 <code>content</code> 将被注入到 <code>.popover-body</code> 中。</p>
        <p> <code>.arrow</code> 将成为动态提示框的箭头。</p>
        <p>最外层的包装元素应该有 <code>.popover</code>。</p>
      </td>
    </tr>
    <tr>
      <td>title</td>
      <td>string | element | function</td>
      <td>''</td>
      <td>
        <p>如果 <code>title</code> 属性不存在，则为预设标题值。</p>
        <p>如果给出一个函数，它将被调用，其 <code>this</code> 引用设置为动态提示框附加到的元素。</p>
      </td>
    </tr>
    <tr>
      <td>trigger</td>
      <td>string</td>
      <td>'click'</td>
      <td>
      如何触发动态提示框 - click | hover | focus | manual。 你可以传递多个触发器；将它们与空格分开。`manual` 不能与任何其他触发器组合。</td>
    </tr>
    <tr>
      <td>offset</td>
      <td>number | string</td>
      <td>0</td>
      <td>
      动态提示框相对于其目标的偏移。更多信息，请参阅 Popper.js 的 <a href="https://popper.js.org/popper-documentation.html#modifiers..offset.offset">偏移文档</a>。</td>
    </tr>
    <tr>
      <td>fallbackPlacement</td>
      <td>string | array</td>
      <td>'flip'</td>
      <td>
      指定动态提示框将在调回时使用哪个位置。 有关更多信息，请参阅 Popper.js 的 <a href="https://popper.js.org/popper-documentation.html#modifiers..flip.behavior">行为文档</a></td>
    </tr>
    <tr>
      <td>boundary</td>
      <td>string | element</td>
      <td>'scrollParent'</td>
      <td>Overflow constraint boundary of the popover. Accepts the values of <code>'viewport'</code>, <code>'window'</code>, <code>'scrollParent'</code>, or an HTMLElement reference (JavaScript only). For more information refer to Popper.js's <a href="https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement">preventOverflow docs</a>.</td>
    </tr>
  </tbody>
</table>
  

<div class="bd-callout bd-callout-info">
<h4 id="data-attributes-for-individual-popovers">各弹出框的data属性</h4>

<p>如上所述，可以通过使用data属性来替代指定各个弹出框的选项。</p>
</div>

<h3 id="methods">方法</h3>

<div class="bd-callout bd-callout-danger">
<h4 id="asynchronous-methods-and-transitions">Asynchronous methods and transitions</h4>

<p>All API methods are <strong>asynchronous</strong> and start a <strong>transition</strong>. They return to the caller as soon as the transition is started but <strong>before it ends</strong>. In addition, a method call on a <strong>transitioning component will be ignored</strong>.</p>

</div>

<h4 id="popoveroptions"><code class="highlighter-rouge">$().popover(options)</code></h4>

<p>元素集合的弹出框初始化。</p>

<h4 id="popovershow"><code class="highlighter-rouge">.popover('show')</code></h4>

<p>显示一个元素的弹出框。 <strong>在弹出实际显示之前返回给调用者</strong> （即，在<code class="highlighter-rouge">shown.bs.popover</code>事件发生之前）。 这被认为是弹出框是 “手动” 触发。标题和内容均为零的弹出框从不显示。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'show'</span><span class="p">)</span></code></pre></figure>

<h4 id="popoverhide"><code class="highlighter-rouge">.popover('hide')</code></h4>

<p>隐藏元素的弹出框。<strong>在弹出框实际被隐藏之前返回给调用者</strong> (即，在 <code class="highlighter-rouge">hidden.bs.popover</code> 事件发生之前）。这被认为是弹出框的 “手动” 触发。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'hide'</span><span class="p">)</span></code></pre></figure>

<h4 id="popovertoggle"><code class="highlighter-rouge">.popover('toggle')</code></h4>

<p>切换元素的弹出框。 <strong>在popover实际显示或隐藏之前返回给调用者</strong>（即，在 <code class="highlighter-rouge">shown.bs.popover</code> 或 <code class="highlighter-rouge">hidden.bs.popover</code> 事件发生之前）。 这被认为是弹出框的 “手动” 触发。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'toggle'</span><span class="p">)</span></code></pre></figure>

<h4 id="popoverdispose"><code class="highlighter-rouge">.popover('dispose')</code></h4>

<p>隐藏和销毁一个元素的弹出框。使用委託（<a href="#options">the <code class="highlighter-rouge">selector</code> option</a>) 创建）的弹出框不能在后代触发元素上被单独销毁。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'dispose'</span><span class="p">)</span></code></pre></figure>

<h4 id="popoverenable"><code class="highlighter-rouge">.popover('enable')</code></h4>

<p>给一个元素的弹出框显示的功能。 <strong>弹出框是在预设情况下添加的。</strong></p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'enable'</span><span class="p">)</span></code></pre></figure>

<h4 id="popoverdisable"><code class="highlighter-rouge">.popover('disable')</code></h4>

<p>删除要显示元素的弹出框的功能。只有在重新添加后，才能显示弹出框。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'disable'</span><span class="p">)</span></code></pre></figure>

<h4 id="popovertoggleenabled"><code class="highlighter-rouge">.popover('toggleEnabled')</code></h4>

<p>切换弹出框的显示或隐藏元素功能。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'toggleEnabled'</span><span class="p">)</span></code></pre></figure>

<h4 id="popoverupdate"><code class="highlighter-rouge">.popover('update')</code></h4>

<p>更新弹出框的位置。</p>

<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#element'</span><span class="p">).</span><span class="nx">popover</span><span class="p">(</span><span class="s1">'update'</span><span class="p">)</span></code></pre></figure>

<h3 id="events">事件</h3>

<table class="table table-bordered table-striped">
  <thead>
    <tr>
      <th style="width: 150px;">事件类型</th>
      <th>描述</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>show.bs.popover</td>
      <td>
      当调用 <code>show</code> 实例方法时，此事件会立即触发。
      </td>
    </tr>
    <tr>
      <td>shown.bs.popover</td>
      <td>
      当弹出框显示时，会触发此事件（待 CSS 转换完成）。</td>
    </tr>
    <tr>
      <td>hide.bs.popover</td>
      <td>当调用 <code>hide</code> 实例方法时，会立即触发此事件。</td>
    </tr>
    <tr>
      <td>hidden.bs.popover</td>
      <td>
      当弹出框隐藏后，会触发此事件（将等待CSS转换完成）</td>
    </tr>
    <tr>
      <td>inserted.bs.popover</td>
      <td>当将提示范本加到 DOM 时，此事件在 <code>show.bs.popover</code> 事件之后触发。</td>
    </tr>
  </tbody>
</table>
<figure class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">$</span><span class="p">(</span><span class="s1">'#myPopover'</span><span class="p">).</span><span class="nx">on</span><span class="p">(</span><span class="s1">'hidden.bs.popover'</span><span class="p">,</span> <span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
  <span class="c1">// do something…</span>
<span class="p">})</span></code></pre></figure>
</div>

